Implement initial PyAutoBrain Build Agent - #3

Summary

Adds the Build Agent — the second canonical PyAutoBrain reasoning agent and the reference example of the Brain coordinating multiple organs. It is the executive/orchestration layer for execution work: it owns the build workflow but delegates the building to PyAutoBuild and the health decision to the Health Agent. It reasons; PyAutoBuild executes.

Implements the task in PyAutoMind/feature/pyautobrain/build.md.

Architecture

The centrepiece: Brain agents consult one another. The Build Agent does not query PyAutoHeart directly — it consults the sibling Health Agent, and only the Health Agent talks to the Heart organ.

Mind  →  Build Agent  →  Health Agent  →  Heart  →  GREEN/YELLOW/RED
                      →  Build Agent  →  PyAutoBuild (execute)

This generalises to a future society of agents (Feature Agent asks Health Agent about refactor readiness; Release Agent asks Build Agent to package).

Release as a mode, with a clean seam

Release is in scope today (PyAutoBuild owns release/build/deploy execution) but isolated as a mode, so release-specific reasoning never bleeds into generic build execution and can split into a dedicated Release Agent later — one agent now, clean seam for two later.

An unknown verdict collapses to YELLOW — never silently GREEN.

Files

• agents/build/build.sh — deterministic entrypoint. Parses mode/action, consults the Health Agent, applies the per-mode gate, emits a structured BuildDecision (JSON), then delegates to the matching autobuild capability. --dry-run plans without executing.
• agents/build/AGENTS.md — concise agent doc (<200 lines) incl. the BuildDecision schema and mode/gate table.
• agents/build/BUILD_CAPABILITIES.md — audit of every PyAutoBuild execution capability the agent calls, plus the boundary finding: the health-shim commands (verify_install, url_check, watch/status/tick/fix) belong to Heart and are refused here, reached via pyauto-brain health.
• agents/_common.sh — consult_health_agent_verdict helper (agent-to-agent consult, pipefail-safe).
• bin/pyauto-brain — register the build agent (listed first).
• README.md, AGENTS.md — document the organism, multi-organ coordination, the society-of-agents pattern, and the future Release Agent split.

BuildDecision

{
  "agent": "build",
  "mode": "build|deploy|release",
  "requested_action": "<PyAutoBuild capability>",
  "health_status": "green|yellow|red|unknown",
  "decision": "proceed|proceed-with-caution|abort",
  "execution_plan": ["autobuild <action> <args>"],
  "execution_summary": "<one line>",
  "warnings": ["..."],
  "blockers": ["..."],
  "follow_up_recommendations": ["..."],
  "dry_run": false
}

Validation

Exercised end-to-end with stubbed Heart/autobuild:

• dispatcher listing, help, help build, build --help, pyauto-agent back-compat shim
• every gate path (green/yellow/red/unknown) across all three modes
• --dry-run (plan only, no execution)
• health-shim rejection (build tick → pointed at pyauto-brain health)
• invalid mode / invalid action for mode
• full GREEN happy path delegating to a stubbed autobuild with forwarded args
• RED correctly aborts (exit 3, autobuild never runs)
• all .md files under the 200-line guidance; bash syntax checks pass

No existing functionality regresses — every PyAutoBuild execution capability remains usable through the Build Agent.

🤖 Generated with Claude Code

Generated by Claude Code